docs: Add details

Explain the difference between GtkPicture and GtkImage,
and when you might want to use which.

diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index 730660ff06ae635787fd1d933a7695b3467bab26..5c53a5ede1a9138f9518d122a642b36478e42240 100644 (file)
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -44,7 +44,7 @@
  * SECTION:gtkimage
  * @Short_description: A widget displaying an image
  * @Title: GtkImage
- * @SeeAlso: #GdkTexture
+ * @SeeAlso: #GdkTexture, #GtkPicture
  *
  * The #GtkImage widget displays an image. Various kinds of object
  * can be displayed as an image; most typically, you would load a
@@ -67,6 +67,10 @@
  * In this case, the #GtkImage:resource, gtk_image_new_from_resource() and
  * gtk_image_set_from_resource() should be used.
  *
+ * GtkImage displays its image as an icon, with a size that is determined
+ * by the application. See #GtkPicture if you want to show an image at is
+ * actual size.
+ *
  * # CSS nodes
  *
  * GtkImage has a single CSS node with the name image. The style classes

diff --git a/gtk/gtkpicture.c b/gtk/gtkpicture.c
index 6f0eb83240a4af78679fec3527170731df90acf2..0668cad14b250c0aa59f93b45898762aa0009490 100644 (file)
--- a/gtk/gtkpicture.c
+++ b/gtk/gtkpicture.c
@@ -56,6 +56,9 @@
  * In this case, gtk_picture_new_for_resource() and gtk_picture_set_resource()
  * should be used.
  *
+ * GtkPicture displays an image at its natural size. See #GtkImage if you want
+ * to display a fixed-size image, such as an icon.
+ *
  * # Sizing the paintable
  *
  * You can influence how the paintable is displayed inside the #GtkPicture.